Resource Library: Multimedia

home *** CD-ROM | disk | FTP | other *** search

/ Resource Library: Multimedia / Resource Library: Multimedia.iso / hypertxt / msdos / hs25 / hsbase.lzh / HS.DOC < prev next >

Wrap

Text File | 1989-05-13 | 27.3 KB | 1,124 lines

HyperShell Hypertext control system Version 2.5 Users Guide Copyright (c) 1988,1989 Text Technology Text Technology 66 Kennedy Avenue Macclesfield Cheshire England SK10 3DE - 1 - Chapter 1 Using HyperShell 1.1 Introduction This manual is a guide to the use of the HyperShell system for the end user. An 'end user' is someone who uses the HyperShell program with supplied hyperfiles. It describes the invocation mechanism, and the interaction capabilities provided for the user. This document is also an essential primer for the HyperShell Author. The production of HyperShell files is described in the Authoring Guide. The format of HyperShell files is described in the Authors reference guide. The hypertext concept and the HyperShell product are described in the Shareware notice document. 1.2 Invocation To use certain features of HyperShell, it is necessary to have the COMSPEC environment variable and the PATH environment variable set up correctly. Refer to your machine instructions for details of how to check this. The PATH environment variable needs to include the disk and directory where the programs to be run reside. If a number of applications are to be run using HyperShell as a menu system, the FILES statement in the CONFIG.SYS file may need extending to cover all files that could be open at once. To invoke HyperShell from the DOS command line, type - 2 - HyperShell Using HyperShell User Manual HS {options} hyperfile {frame} The hyperfile parameter is the name of the file to view using HyperShell. It can have an extension if needed (the default is .HYP). If your hyperfiles are in a special directory elsewhere on the same or another disk, you should set up an environment variable using the SET command (See your DOS manual) of the form:- SET HSPATH=C:\HYPER\ The bracketed parameters are optional. {options} are one or more of the following:- -n Create notepad file if it doesn't exist -s Save screen for redisplay during session and on exit -m Attempt to use mouse driver directly -f Suppress the display of guide symbols on menus -b Suppress the retention of backtrack information -a Switch on autoreferencing -r Display available memory on exit -x Suppress filename suffix on frames in reference list -t Trace labels in scripts -h MDA/Hercules highlighting scheme -g CGA/EGA highlighting scheme -z Flash mouse cursor -l Don't highlight references when using Type file option -k Don't highlight refs and strip 8th bit -d Use BIOS for display (only if desperate) {frame} is the name of a frame to display initially. The first frame in the hyperfile is otherwise displayed. The -n option indicates that any notepad information should be saved on exit to a file called NOTES.HSN. If this file already 1-3 Version 2.5 HyperShell Using HyperShell User Manual exists at startup, it is read into the notepad store, and saved on exit. This facility permits the references in the notepad to be retained between invocations. The -d option uses BIOS calls for screen display, and should only be used on those machines that are not sufficiently compatible to work with direct screen display. Some trivial display errors can occur when using -d. The -r and -t options are for use by hyperfile authors, and are not normally of use to the end user. The display adapter will be automatically sensed and an appropriate highlighting scheme adopted. The scheme can be forced to the colour schemes using the -g option, or to the monochrome schemes using -h. The -z option, default for monochrome displays, can be used with colour displays for flashing the mouse cursor to make it more visible (in emulation mode only). The -l and -k options permit files listed using the 'T' action (Type file) to be listed verbatim without the references expanded. The -k option also strips the 8th bit for typing WordStar(tm) format files. 1.3 Interaction Interaction with HyperShell is normally done using the mouse. A typical application of HyperShell would only require occasional use of the keyboard, but more advanced uses may well require heavier use of the keyboard. Having said that, if you haven't got a mouse, you need to use the keyboard all the time. There is a 'mouse emulator' provided, to allow you to use the cursor keys to move about, and also a number of standard, and application tailorable, key mappings are provided. 1.3.1 The Mouse If you have a mouse, and wish to use the mouse emulator, to get the additional features, set it up so that it drives the cursor keys, and maps the left/right buttons to RETURN/ESCAPE. Specifying the -m option on the command line attempts to connect directly to the mouse driver. If use of this option does not 1-4 Version 2.5 HyperShell Using HyperShell User Manual lead to proper mouse interaction, it should not be used. Any Microsoft compatible mouse should be supported. Positioning On startup, HyperShell positions the mouse cursor (A square block) in the centre of the screen. Moving the mouse will move this block. You would typically move the mouse to a highlighted reference and select it. Buttons The left mouse button, and the RETURN key, selects the reference over which the mouse cursor is positioned. If a menu is presented for selection, the left button is pressed over a choice to select it, or pressed outside the menu to cancel the menu (but see below). The right mouse button, and the ESCAPE key, has two differing actions depending upon when it is pressed. When reading a normal frame display, this button causes the main HyperShell control menu to appear. When it is pressed during the display of a menu, a popup message, a note or a paged display, it cancels that item. When it is pressed during one of these displays in the execution of a script, it also cancels the rest of the script. 1.3.2 The Keyboard The keyboard is by no means a poor substitute for the mouse, and provides as powerful a control as the mouse when used properly (by the application as well as the user). The mouse emulator allows the cursor keys to move the mouse cursor around, but this is not as convenient as the mouse itself. To compensate for this, shortcuts are provided for cursor positioning and selection. 1-5 Version 2.5 HyperShell Using HyperShell User Manual Standard keys Certain keys are available whether the mouse is available or not. The RETURN key is used for selections, as well as for terminating typed responses to prompts and input fields. The ESCAPE key is used as a cancel key, and has the same effect as the right mouse button. The Home, PgUp and PgDn keys are used during paged displays, to move the display to the previous/next display (PgUp is not always available!). The Home key and PgDn key are also used when displaying a frame text which is longer than a screenful, to move to the first screen and the next screen respectively. The End key is used during a frame display to recall the screen saved on entry if the -s command line option was used. This is useful when the hyperfile is being used for a help system, and you want to recall what you wanted help about. Pressing any key returns you to the frame display. The keypad INS and DEL keys are used for inserting references into and removing references from the 'notepad'. This is a list which is maintained during your HyperShell session, and is used to store references that you may not wish to follow immediately, but nevertheless wish to 'note'. The keys are used by pressing them when over the required reference. A message is displayed to show you the results of the action. Pressing the keys when not over a reference, when displaying a frame, will result in the current frame having its reference added to the notepad. The notepad information can be retained between sessions using a notepad file. This can be initially created by using the -n option on the invocation command line. The '?' key is used to ask for help. It will usually display a menu of topics for which help is available. When a topic is selected, a note describing the topic is displayed. The help key is available in frame displays and paged displays. If a particular hyperfile does not support the help key, a message will be displayed to say that the help menu is not available. The F1 key may in some hyperfiles be mapped to the help menu, and in this case may offer more than simple notes from the help menu. 1-6 Version 2.5 HyperShell Using HyperShell User Manual When in mouse emulation mode, the TAB and BACKTAB act as a quick means of stepping through the highlighted references on display. These wrap around the display, moving back to the beginning when they reach the end and vice versa. Function keys Function keys may be mapped by a particular hyperfile. Unshifted function keys are always mapped to the control actions provided by the main control menu. The three shifts applied against the function keys are generally mapped depending on a particular applications requirements. By convention, an application provides a help display of actions mapped to the function keys. Other keys The keys in the normal ASCII printable set may also be mapped to actions although this is not normally done because of the number of function keys provided. The frame text reference specification allows a key to be mapped to a highlighted reference. This can be nearly any key or shift/key combination available that is not mapped to an action. Normally an alphabetic character is used for this purpose, being the initial character of the reference. The provision of this facility is sometimes indicated in the frame text by a reminder of the form '[x]' to the left of the reference for which the 'x' key is mapped. 1.4 Moving about The normal HyperShell display presents a full screen display consisting of a header, fixed in format for any particular hyperfile, a frame text section, containing the frame text for a topic, and a footer, also fixed in format for a particular hyperfile. Any of these sections can contain highlighted words, 1-7 Version 2.5 HyperShell Using HyperShell User Manual which can be selected to perform various actions. These are known as 'references'. 1.4.1 References References are highlighted in some way to make them stand out from the rest of the text. It may also be the case that highlighting is used to enhance the appearance of the general display, and items so highlighted are not selectable (you can distinguish these by their lack of action when you attempt to select them - hopefully their content and contextual circumstances will have already told you this before you try). To help you to know what resulting action a reference selection will have, references are highlighted in different ways depending on type. It will not always tell you what type they are, but in the majority of cases it will. Frames Frame references are references to other frames of text, in this or another hyperfile. Selecting one of these adds the current frame reference to the backtrack list and displays the selected one. Another form of frame reference does not cause the current frame reference to be added to the backtrack list before moving to the selected frame. Notes Note references refer to short notes about a particular topic, which popup over the frame display. These can be local to the frame, or local to the hyperfile as a whole. Further selections can be made from notes, and the note will be cleared when any button or key is pressed. A note can be used within a particular hyperfile to obtain information from you by offering a number of choices for selection, in a similar fashion to a menu. 1-8 Version 2.5 HyperShell Using HyperShell User Manual Menus Menu references pop up a menu from which a choice of actions is available. Menus can be local to a frame or local to a hyperfile as a whole. A choice can be made from the menu by moving the mouse cursor to highlight the option, then pressing the left mouse button or the RETURN key, or the menu can be cancelled using the right mouse button or the ESCAPE key. Scripts A script is a sequence of actions. These can be any of the available actions. A script can be cancelled whenever the computer is awaiting an input, by use of the ESCAPE key. The presence of scripts is not always obvious to the end user. Actions An action reference is used to show that some action other than one of the above will be performed when it is selected. Normally the content or context of the reference will give some clue as to the likely outcome of selection. Input fields Input fields, when selected, allow a string to be entered. The string is accepted when the RETURN key is pressed, or when the string reaches the length of the field. The ESCAPE key cancels the input. Input fields are generally used to input variables, but may be used for almost any action. 1-9 Version 2.5 HyperShell Using HyperShell User Manual 1.4.2 Colours/defaults The following default colour scheme is used for references. Those of you with monochrome display adaptors should think seriously about upgrading to something more modern, but you can use an alternative set of highlighting schemes by specifying the -h option. If your monochrome monitor can show 16 grey shades, you will get used to the highlighting differences through using HyperShell with the normal set. If you don't like the defaults, it is possible to set up alternative schemes by setting the attribute options, either directly or in the hyperfile setup section for your main hyperfile. Frame text display Normal text white on black Default title black on white Frame ref (stack) bright white on black Frame ref (replace) light yellow on black Action reference bright white on blue Script reference light yellow on green Note reference light green on black Menu reference black on white Input field yellow on brown Pop up displays Note heading black on green Note text light yellow on green Menu heading black on red Menu choice black on brown Menu selection light yellow on blue Popup message light yellow on red (blink) Prompted input / message black on white 1.5 Control menu The control menu provides a means of controlling HyperShell where no other key control or references are available. It is also a handy means of accessing control functions. It provides the following actions. 1-10 Version 2.5 HyperShell Using HyperShell User Manual 1.5.1 Home Frame This selects the 'Home' frame in the current hyperfile. This is the first frame defined in the hyperfile, and is usually the introductory frame, containing routes to the other frames. In some hyperfiles, the first menu choice, also mapped to the F1 key, may be used to present the help menu. This is a standard convention for PC compatible software. The key is not mapped in this way by default in HyperShell because certain hyperfiles may not provide a help menu. To select the home frame, if this option is not available, simply select the contents menu (usually F2) and then press 'a' to select the first frame. 1.5.2 Contents This produces a paged list of contents, from which you can select a frame as a frame reference in the normal way. 1.5.3 Backtrack This displays the frame you were displaying before selecting the current frame. Repeated selection takes you back to the original frame you were displaying, one step at a time. When you reach the start, a message will be displayed to tell you that you are at the beginning of the list. Certain frame references may control the stacking of backtrack information, and cause the top entry to be overwritten rather than stacked. This will mean that not all frames visited will be available on the backtrack list. References for these frames, called 'replace' frame references, are highlighted in yellow rather than white when displayed in text. 1.5.4 Select back This produces a paged list of frames you have visited on the way to displaying the current frame, and allows you to return to displaying any of these frames, by simply selecting it as a reference. 1-11 Version 2.5 HyperShell Using HyperShell User Manual 1.5.5 Notepad This presents a paged display of references inserted by you into the notepad list. These references can be selected to action them at any time after they have been noted, although certain of them will only be available if you are using the same hyperfile as you were when you inserted them. References can be removed from the list by pressing the keypad DEL key when positioned over the reference. As mentioned previously, the notepad can be retained between sessions using the notepad file. 1.5.6 Search Text This prompts for a search string, and then searches the current hyperfile for a frame containing the search string in its title or text. The search operation can be stopped by pressing any key. 1.5.7 Type file This produces a paged display of a text file. If the text file contains any embedded reference annotation, this will be highlighted, and you can select this to display frames, notes or other items from the current hyperfile. If 'autoreferencing' is switched on, references in the text file that match any of the frame names in the current hyperfile will be highlighted as frame references. You can use the PgUp, PgDn, and Home keys to page up and down the file, and to move to the start of the file. The End key will cancel the file display without having any further cancel action. The ESCAPE key will cancel the file display, along with any currently executing script. The '#' key will prompt for a page number, and will position at that page. The '/' key will prompt for a search string, and will search from the next page forward until it finds the string in the file text, whereupon it will highlight the line containing the string and stop. Pressing a key during one of these searches will stop the search and display the page currently being searched. When you reach the end of the file, a message will flash to tell you that you have reached the end. When this occurs pressing anything other than the above keys will cause the file to be closed and the last frame displayed to be shown. 1-12 Version 2.5 HyperShell Using HyperShell User Manual Selecting a reference, or pressing the left mouse button (or RETURN) displays the reference or the last frame viewed. To return to viewing the file, select 'Type File' on the control menu again. 1.5.8 Do action This allows the more expert HyperShell user to directly enter action commands. See the list of actions in the Authoring Guide for details of what actions are available. An example is 'Fframename', where framename is the name of a frame in the current hyperfile, which displays the named frame. 1.5.9 DOS Shell This runs a DOS command processor, to allow you to run programs from the DOS command line and return to HyperShell afterwards, by typing EXIT at the DOS command prompt. 1.5.10 Exit to DOS This causes HyperShell to terminate. If it was invoked with the -s option, it will redisplay the screen as it was when you entered HyperShell. 1.6 Paged displays Paged displays are displays of information which may take more than one screenful to display. The 'Type File' display is a paged display, and allows movement up and down the file, searching etc. Other paged displays are used for the various lists - contents list, notepad list, backtrack list etc, as well as extended directory listings. Whilst viewing a paged display, you may use certain keys as indicated by the heading line. 'Paging' implies that the Pg Up, Pg Dn and Home keys can be used to move to the previous page, next page, and first page of the list respectively. [key] indicates that the unshifted letter keys indicated down the left side of the list can be used to select items in the list. The Escape key can be used to cancel the list and return to the frame display. 1-13 Version 2.5 HyperShell Using HyperShell User Manual Also available during paged displays are the function keys. These are mapped to functions consistent with the default values during the frame display. F1 - help, F2 - page number, F3 - previous page, F6 - search, F9 - temporary exit paged display, F10 - quit paged display. Not all these keys are available for all paged displays, and will cause a next page operation if not available for a particular display. 1.7 Error messages 1.7.1 Popup A number of popup messages can appear - some from HyperShell itself, and some from hyperfiles doing a 'popup message' action. When you have read a popup message, press any key to cancel it. The ones that HyperShell displays are as follows:- At beginning of list You have reached the start of the backtrack list and cannot backtrack any further. {Item} is not available Where item is one of Frame, Note, Menu, Script, File. The reference you have selected directly or indirectly refers to the name of an item that does not exist. An inconsistent hyperfile text is the probable cause for this. Continuing file {filename} You have asked for a file to be typed, when there is currently one being processed. To cancel the continued file display, press the right mouse button (or the ESCAPE key). 1.7.2 Error codes The error code variable '?' is set whenever certain errors occur. It may be displayed using the command 'P$?' at the DO ACTION prompt. The codes, with their associated meanings, are listed in the Appendix. 1-14 Version 2.5 HyperShell Using HyperShell User Manual 1.7.3 Fatal These messages appear when a situation occurs where it is not practical to continue running HyperShell. They are as follows:- Out of memory - code nnn HyperShell ran out of memory when attempting to allocate some for an item. You were probably running a lot of hyperfiles, or a large hyperfile (see restrictions in Authoring Guide). Try again with less. Can't open file {filename} The initial hyperfile requested cannot be opened. Check that you have its name correct, that you have drive and directory paths if needed, or have the HSPATH environment variable set. 1.7.4 Other problems If something does not appear to work correctly, check that the various environment variables are set up correctly as described in the first section. If the COMSPEC and PATH variables are not set up, programs cannot be run from HyperShell, and the DOS EXIT cannot be used. To check the error status try entering the action 'p$^', which will display the current error number, which can be checked against the list in the Authors guide, or reported to the supplier of the hyperfile. 1.8 Error codes 1 - Operation cancelled 2 - Menu no choice 3 - End of file 4 - Cant open file 5 - File not open 6 - File open 7 - File changed 8 - At start of backtrack 9 - Divide by 0 10 - Value not expected 1-15 Version 2.5 HyperShell Using HyperShell User Manual 11 - Value expected 12 - Undefined opcode 13 - Unmatched parenthesis 14 - Syntax error 15 - Script not available 16 - Menu not available 17 - Note not available 18 - Frame not available 19 - Key not defined 20 - Invalid key code 21 - Local ref can't be noted 22 - Not at reference 23 - Key not mapped 24 - No action or disabled 25 - Invalid action code 26 - No command 27 - Env var not present 28 - Invalid dynamic menu 29 - Line too wide for screen 30 - String too long 31 - Too many lines in frame 32 - Max script reached 33 - Maximum menu size reached 1-16 Version 2.5 HyperShell Using HyperShell User Manual Table of Contents Chapter 1 Using HyperShell 2 1.1 Introduction 2 1.2 Invocation 2 1.3 Interaction 4 1.3.1 The Mouse 4 1.3.2 The Keyboard 5 1.4 Moving about 7 1.4.1 References 8 1.4.2 Colours/defaults 10 1.5 Control menu 10 1.5.1 Home Frame 11 1.5.2 Contents 11 1.5.3 Backtrack 11 1.5.4 Select back 11 1.5.5 Notepad 12 1.5.6 Search Text 12 1.5.7 Type file 12 1.5.8 Do action 13 1.5.9 DOS Shell 13 1.5.10 Exit to DOS 13 1.6 Paged displays 13 1.7 Error messages 14 1.7.1 Popup 14 1.7.2 Error codes 14 1.7.3 Fatal 15 1.7.4 Other problems 15 1.8 Error codes 15 1-17 Version 2.5